Skip to content

docs: refresh two stale facts against their code arbiters - #178

Merged
argszero merged 1 commit into
mainfrom
docs/refresh-stale-facts
Sep 12, 2026
Merged

docs: refresh two stale facts against their code arbiters#178
argszero merged 1 commit into
mainfrom
docs/refresh-stale-facts

Conversation

@argszero

Copy link
Copy Markdown
Owner

Summary

Two statements in docs/ no longer match the code that owns them. Both files self-describe as current state (architecture.md: 「本文说明现状」;plan-api-matrix.md: 「协议支持现状」), so stale numbers there are read as facts by new contributors. This PR refreshes them and — more importantly — makes each line point at its arbiter instead of retyping the value, so the next drift is visible at the point of editing.

The two errors have different provenance, which is why both are worth recording:

  • docs/architecture.md — "迁移 v10" → v12. Correct when written, then went stale. The text was accurate at commit 6d87213 (git show 6d87213:src/db.rs really was SCHEMA_VERSION = 10); v11 and v12 landed afterwards (v12 = the transactions performance indexes, rant 2026-08-25T12:02:13, PR fix(perf): warm NFS sqlite with 64MB cache + transactions indexes + parallel trend (rant 2026-08-25T12:02:13) #150) and nothing pointed the doc back at the constant.
  • docs/plan-api-matrix.md — "13 个模型" → 14. Wrong the moment it was written. The model deepseek-v4-flash-vision-exp was added in 2474f87 (2026-08-22 06:19); the doc text arrived in 6d87213 (2026-08-22 08:06), 1h47m later. Replaying that commit settles it — git show 6d87213:config/config.example.toml has 14 [[models]] and git show 6d87213:ui/js/data.js has 14 MODELS. So "13" matches no set that ever existed alongside that sentence; the 13-model state is 2474f87^.

The 14 figure is not my count, it is already a guarded contract in-repo: src/catalog_gate.rs pins MODEL_COUNT: usize = 14 (added by #173) and catalog_gate.rs/i18n_pack.rs run on every cargo test. The doc was contradicting a gate that had been in place since the same week.

Related Issue

Changes

  • docs/architecture.md: 数据库 row — 「迁移 v10」→「幂等迁移至 v12,见 src/db.rsSCHEMA_VERSION
  • docs/plan-api-matrix.md §4: 「13 个模型」→「14 个模型」,并注明真源(config/config.example.toml[[models]])与守卫(src/catalog_gate.rsMODEL_COUNT
  • 涉及配置/数据结构的改动已同步示例文件 — not applicable: no config, schema, or code changed

Scope: exactly two files, both Markdown. No Rust source, no ui/, no i18n keys, no cache-bust. git diff HEAD -- . ':(exclude)docs/' is empty.

Tests

  • cargo test 全部通过 — 165 passed / 0 failed

  • cargo fmt --check 通过;cargo clippy --all-targets -- -D warnings 无 warning

  • 新增/更新了单元测试(如适用)— not applicable for a Markdown-only change. Instead every fact asserted by the two edited lines was checked mechanically against its arbiter, with a negative control:

    Asserted by the doc Arbiter Result
    schema at v12 src/db.rs SCHEMA_VERSION = 12
    catalog = 14 models config/config.example.toml [[models]] 14 ✓
    catalog = 14 models src/catalog_gate.rs MODEL_COUNT = 14
    catalog = 14 models ui/js/data.js MODELS 14 ✓
    "no longer says v10 / 13" the edited files themselves old strings absent ✓

    Negative control: replaying the same checks against a copy with the value perturbed fails, so the assertions are not vacuous.

Checklist

  • 分支命名符合约定 — docs/refresh-stale-facts (docs/ per CONTRIBUTING.md)
  • Commit message 使用 Conventional Commits 格式 — docs: refresh two stale facts against their code arbiters (bare docs: matching the repo's precedent in 6d87213 for multi-file doc changes)
  • 单一职责,改动最小化 — one theme: stale current-state facts in docs/

docs/architecture.md said the SQLite file was at "migration v10" while
src/db.rs has SCHEMA_VERSION = 12 (v11/v12 landed after that text was
written), and docs/plan-api-matrix.md said "13 个模型" while the catalog
has held 14 since deepseek-v4-flash-vision-exp was added -- the doc commit
6d87213 postdates that model by 1h47m.

Both lines now quote the arbiter instead of retyping the fact, so the next
drift is visible: SCHEMA_VERSION for the schema, [[models]] plus
catalog_gate's MODEL_COUNT for the catalog.
@argszero
argszero merged commit 3b1c0b0 into main Sep 12, 2026
1 check passed
@argszero
argszero deleted the docs/refresh-stale-facts branch September 12, 2026 05:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant